<HTML><HEAD><TITLE>substring(+String1, ?Position, ?Length, ?String2)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Strings and Atoms</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>substring(+String1, ?Position, ?Length, ?String2)</H1>
Succeeds if String2 is the substring of String1 starting at position
Position and of length Length.


<DL>
<DT><EM>String1</EM></DT>
<DD>String.
</DD>
<DT><EM>Position</EM></DT>
<DD>Integer (from 1 upwards) or variable.
</DD>
<DT><EM>Length</EM></DT>
<DD>Integer (from 0 upwards) or variable.
</DD>
<DT><EM>String2</EM></DT>
<DD>String or variable.
</DD>
</DL>
<H2>Description</H2>
   Succeeds if String2 is a substring of String1 starting at position
   Position and of length Length.

<P>
   On backtracking, all such substrings are found.

<P>
   The first character of a string is at position 1.

<P>
Note
   If String1 and String2 are instantiated, it is more efficient to use the
   predicates substring/3 and/or string_length/2.

<P>

<H3>Modes and Determinism</H3><UL>
<LI>substring(+, +, +, -) is semidet
<LI>substring(+, +, -, -) is nondet
<LI>substring(+, -, +, -) is nondet
<LI>substring(+, -, -, +) is nondet
<LI>substring(+, -, -, -) is multi
</UL>
<H3>Fail Conditions</H3>
String1 does not have a substring at the required position and/or of the required length, or String2 does not occur within String1
<H3>Exceptions</H3>
<DL>
<DT><EM>(5) type error </EM>
<DD>String1 is instantiated, but not to a string.
<DT><EM>(5) type error </EM>
<DD>String2 is neither a string nor a variable.
<DT><EM>(5) type error </EM>
<DD>Either (or both) of Position or Length are neither integers    nor variables.
<DT><EM>(4) instantiation fault </EM>
<DD>String1 is not instantiated.
</DL>
<H2>Examples</H2>
<PRE>
Success:
  substring("abcabc",3,1,"c").
  substring("abcabc",6,1,"c").
  substring("abcabc",P,1,"c"). (gives P=3; P=6).
  substring("abcabc",3,3,S).   (gives S="cab").
  substring("abc",P,L,"b").    (gives P=2, L=1).

  [eclipse]: substring("ab",P,1,S).
  P=1
  S="a"     More? (;)
  P=2
  S="b"
  yes.

  [eclipse]: substring("ab",1,L,S).
  L=0
  S=""      More? (;)
  L=1
  S="a"     More? (;)
  L=2
  S="ab"
  yes,

  [eclipse]: substring("ab",P,L,S), writeq((P,L,S)), nl, fail.
  1 , 0 , ""            % on backtracking, returns all
  1 , 1 , "a"           %   substrings of String1.
  1 , 2 , "ab"
  2 , 0 , ""
  2 , 1 , "b"
  3 , 0 , ""
  no (more) solution.

Fail:
  substring("joey",P,L,"joy").
  substring("joey",P,2,"joe").

Error:
  substring(S1,P,L,S2).                (Error 4).
  substring(S1,1,2,"bc").              (Error 4).
  substring(S1,1,2,'str').             (Error 4).
  substring('string',2,3,S2).          (Error 5).
  substring("string",2,3,'str').       (Error 5).
  substring("string",0,L,S2).          (Error 6).
  substring("string",1,-1,S2).         (Error 6).



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/stratom/substring-3.html">substring / 3</A>, <A HREF="../../kernel/stratom/substring-5.html">substring / 5</A>, <A HREF="../../kernel/stratom/string_length-2.html">string_length / 2</A>, <A HREF="../../kernel/stratom/split_string-4.html">split_string / 4</A>
</BODY></HTML>
